home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / curses.arc / curses.doc < prev    next >
Text File  |  1987-08-24  |  33KB  |  851 lines
  1.            The CURSES screen updating and cursor movement package.
  2.  
  3.           A collection of C-functions for Atari ST-series computers
  4.  
  5.                                Version 1.0
  6.  
  7.  
  8.                              R. van 't Veen 
  9.  
  10.  
  11.  
  12.  
  13.     This document describes a set of C-functions which allow the user
  14. easier design of full-screen applications. This package is intended for
  15. programs that perform graphics-like operations on terminal screens.
  16. It is largely compatible with the UN*X curses(3x) package. This document
  17. provides pointers to its use, a little detail about its inner workings and it
  18. stresses differences between the UN*X-implementation and the Atari-ST series
  19. implementation.
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.    Introduction.
  27.    
  28.    This package was born out of my desire to make more programs available for
  29. UN*X also available on my Atari. A side-effect of this is that it provides
  30. easier screen updating than by means of sending escape codes. The package is
  31. also quite fast, timing of a sample application yielded a rate of about
  32. 90 kilobaud per second.
  33.  
  34.    Terminology.
  35.    
  36.    Throughout this document  the following words will be used frequently :
  37.  
  38. WINDOW       An internal representation of what a section of the terminal
  39.        screen may eventually look like. A window is a rectangular
  40.              array, which may be as big as the terminal screen or even as 
  41.              small as a single character.
  42.  
  43. TERMINAL     Or terminal screen, the packages idea of what the Atari's VT52
  44.      emulation looks like. If everything is allright this is what you
  45.              see. The terminal screen is a special screen.
  46.  
  47. SCREEN       A screen is an element of the set of windows that are as large as 
  48.        the terminal screen. One screen, called stdscr, is already
  49.              provided for.
  50.  
  51.    Using the package.
  52.    
  53.    To use the package, include the file "curses.h" in your source. This gives
  54. you the types and definitions necessary to be able to use it. After compilation
  55. one should link with the file containing the compiled curses-source, as well as
  56. with the object-file or library giving you access to the system calls,
  57. gemdos, bios and xbios. You also should link in a file giving you access
  58. to the malloc() and free() calls. ( Note : this is not the GEMDOS Malloc/Mfree
  59. pair, but a malloc() and free(), which should be contained in any decent
  60. standard C-function library. GEMDOS Malloc/Mfree are very buggy indeed.)
  61. There is a difference with UN*X here : the UN*X-curses includes stdio.h
  62. and sgtty.h, whereas Atari-curses includes portab.h and stdio.h. This should
  63. give you the definitions for BYTE, WORD and LONG. 
  64.  Some compilers supply default startup files that don't supply enough heap space
  65. to run curses in, you should adapt these startup files to your liking.
  66.  
  67.    Installing the package.
  68.    
  69.    Compile the file "curses.c" with your favorite C-compiler, to create an
  70. object-file or library, whatever you prefer. Curses.c includes "portab.h"
  71. for BYTE, WORD, LONG, and NULL definitions, osbind.h for system-call macros
  72. and curses.h for its own definitions. Remember curses.h also includes stdio.h.
  73. The code should be portable between various brands of compilers. Forget about
  74. warnings like : warning : pointer substraction yields a long result. 
  75. Not all compilers adhere to Kernighan and Ritchie standards in this respect.
  76. The meaning of each of the constants is given in the table below. In another
  77. table the used system call macro's are given.
  78.  
  79. +---------------+----------------------------------------------------+
  80. | constant name | meaning                                            |
  81. +===============+====================================================+
  82. | BYTE          | a type with at least 8 bits in it, usually a char  |
  83. | WORD          | a type with at least 16 bits in it                 |
  84. | LONG          | a type with at least 32 bits, used for pointers    |
  85. | NULL          | a value assigned to pointers pointing nowhere      |
  86. +---------------+----------------------------------------------------+
  87.  
  88. +---------------+-----------------------------------------------------+
  89. | macro name    | meaning                                             |
  90. +===============+=====================================================+
  91. | Pterm         | gemdos $4c, terminate process and return to caller  |
  92. | Cconis        | gemdos $0b, console character available ?           |
  93. | Crawcin       | gemdos $07, get a raw character from console        |
  94. | Cnecin        | gemdos $08, get a not-so raw character from console |
  95. | Bconout       | bios $03, output a character to a device            |
  96. | Bconstat      | bios $01, get input device status                   |
  97. | Bconin        | bios $02, input a character from a device           |
  98. | Supexec       | xbios $26, execute function in supervisor mode      |
  99. +---------------+-----------------------------------------------------+
  100.  
  101.    Screen updating.
  102.    
  103.    The package defines a data type called WINDOW, which represents what a
  104. section of the terminal may eventually look like. It can be used as a
  105. scratch-pad onto which you can make changes. Only after calling
  106. the function refresh() or wrefresh() an attempt will be made by the package
  107. to make things on the screen look like the things you specified in the
  108. window. Information contained in the window include not only its contents,
  109. but also its size, its starting point and various other information. Two
  110. standard window are defined after initialization of the package, namely
  111. curscr, which constitutes the package's idea of what the screen looks like,
  112. and stdscr, which is a default window to make changes on. It is advised not
  113. to address curscr directly, but first to make changes on another window and
  114. then to call refresh() or wrefresh() to make curscr look like the other
  115. window. Making a change on curscr results in immediate execution of the
  116. change, this greatly reduces any chances of optimization and therefore results
  117. in a sizeable loss of speed ( unless you know what you're doing, of course ).
  118.  
  119.    Naming conventions.
  120.    
  121.    All output and input functions can be used with any window. These functions
  122. have two variants, one to act on the default screen stdscr, and another to
  123. act on any window. An example is the function addch(), which adds a character
  124. to stdscr. The variant, which adds a character to a window w is called
  125. waddch() and takes w as an argument. This convention is used throughout the
  126. package. The routines which do not adhere to this convention always take a 
  127. window as an argument.
  128.    Apart from the w-convention some functions also take a mv- prefix.
  129. Ordinarily one moves the current coordinates of a window by calling
  130. the move or wmove function. Preceding an I/O function by mv first moves
  131. the current coordinates and then performs the I/O function. In this way
  132. one can write the sequence :
  133.  
  134. move(y,x) ;
  135. addch('Q') ;
  136.  
  137. as :
  138.  
  139. mvaddch(y,x,'Q') ;
  140.  
  141. and the sequence :
  142.  
  143. wmove(win,y,x) ;
  144. waddch(win,'W') ;
  145.  
  146. may be replaced by :
  147.  
  148. mvwaddch(win,y,x,'W') ;
  149.  
  150. You may have noticed the following other conventions :
  151. 1. If a window must be specified as a parameter, it is always the first
  152.    parameter.
  153. 2. Coordinates are specified as (y,x) pairs, where y is in the up/down
  154.    direction, and x in the letf/right direction, the coordinate (0,0) is
  155.    in the upper-left corner of the window.
  156.  
  157.  
  158.    Programming with curses.
  159.    
  160.    The following sections deal with programming with the library.
  161. First of all curses should be initialized first. This is done by a call to
  162. initscr(). On return curses will have initialized the screen to a state known
  163. by curses, and have initialized curscr and stdscr, whereas prior to the
  164. initscr() call, any reference to curscr or stdscr will result in bombs.
  165. After calling initscr() you should perform any terminal status changing
  166. routines like crmode() or nonl(), although these may be performed anytime
  167. when curses is active. After that you can set up the screen status using
  168. functions like leaveok() and scrollok() or allocate new windows with newwin()
  169. or subwin(), delete them with delwin(). 
  170.    Calling initscr() again will either result in a redraw of the screen or
  171. another initialization step when the variables LINES or COLS have changed.
  172. T